{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "e31ea59b-67bd-4fc7-aae0-842e0ec9f1ae",
   "metadata": {},
   "source": [
    "# Violin Plot with Jitter\n",
    "\n",
    "This example combines a violin plot with a jittered scatter overlay to show the distribution and individual values of flipper length across penguin species. The transparent violins provide a summary shape, while the scatter points reveal the underlying data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c979f2ee-d38b-487e-898c-ae0569b2933b",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins('pandas')\n",
    "\n",
    "df.hvplot.violin(\n",
    "    y='flipper_length_mm',\n",
    "    by='species',\n",
    "    title='Violin Plot by Species (Bokeh)',\n",
    "    ylabel='Flipper Length (mm)',\n",
    "    violin_fill_alpha=0\n",
    ") * df.hvplot.scatter(\n",
    "    x='species',\n",
    "    y='flipper_length_mm',\n",
    "    color=\"black\",\n",
    "    alpha=0.7,\n",
    "    size=8,\n",
    ").opts(jitter=0.25)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f3dba609-6156-453c-a634-fa870be9565e",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "import numpy as np\n",
    "\n",
    "hvplot.extension('matplotlib')\n",
    "\n",
    "df = hvplot.sampledata.penguins('pandas')\n",
    "df = df[df['species'].notna()].copy()\n",
    "df = df.sort_values('species')\n",
    "species_map = {'Adelie': 0, 'Chinstrap': 1, 'Gentoo': 2}\n",
    "df['x_jitter'] = df['species'].map(species_map) + np.random.uniform(-0.2, 0.2, size=len(df))\n",
    "\n",
    "df.hvplot.violin(\n",
    "    y='flipper_length_mm',\n",
    "    by='species',\n",
    "    title='Violin Plot by Species (Matplotlib)',\n",
    "    ylabel='Flipper Length (mm)',\n",
    "    edgecolors='black',\n",
    "    facecolors='white',\n",
    ") * df.hvplot.scatter(\n",
    "    x='x_jitter',\n",
    "    y='flipper_length_mm',\n",
    "    color='black',\n",
    "    alpha=0.7,\n",
    "    size=20,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03dd4dc0-ba1e-423b-938e-bc27ad30dc79",
   "metadata": {},
   "source": [
    ":::{note}\n",
    "- In the Bokeh example, `jitter` is a plot option supported by HoloViews.\n",
    "- In the Matplotlib example, the `jitter` plot option is not supported by HoloViews. Therefore, we manually added jitter to the x-axis using random offsets to simulate the effect.\n",
    ":::\n",
    "\n",
    ":::{seealso}\n",
    "- [Violin Plot reference documentation](../../ref/api/manual/hvplot.hvPlot.violin.ipynb).\n",
    "- [Scatter Plot reference documentation](../../ref/api/manual/hvplot.hvPlot.scatter.ipynb).\n",
    ":::"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
